From ed383758c687215b42221826f24f508fc200e75a Mon Sep 17 00:00:00 2001
From: Matthias Clasen <matthiasc@src.gnome.org>
Date: Sat, 2 Aug 2008 04:12:55 +0000
Subject: [PATCH] Improve docs

svn path=/trunk/; revision=20929
---
 ChangeLog                                     |   4 +
 docs/reference/ChangeLog                      |   5 +
 .../gdk/tmpl/gdkapplaunchcontext.sgml         | 106 ++++++++++++++++++
 gdk/gdkapplaunchcontext.c                     |  27 ++++-
 4 files changed, 136 insertions(+), 6 deletions(-)
 create mode 100644 docs/reference/gdk/tmpl/gdkapplaunchcontext.sgml

diff --git a/ChangeLog b/ChangeLog
index 3ed27ba520..552add2bf0 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2008-08-02  Matthias Clasen  <mclasen@redhat.com>
+
+	* gdk/gdkapplaunchcontext.c: Improve the docs
+
 2008-08-01  Claudio Saavedra  <csaavedra@igalia.com>
 
 	Bug 545931 – small documentation typos
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index f4cb42b2e2..1d76720d94 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2008-08-02  Matthias Clasen  <mclasen@redhat.com>
+
+	* gdk/tmpl/gdkapplaunchcontext.sgml: Add an introduction
+	with an example.
+
 2008-07-31  Matthias Clasen  <mclasen@redhat.com>
 
 	* gdk/gdk-sections.txt: Add new api
diff --git a/docs/reference/gdk/tmpl/gdkapplaunchcontext.sgml b/docs/reference/gdk/tmpl/gdkapplaunchcontext.sgml
new file mode 100644
index 0000000000..b1d44035d1
--- /dev/null
+++ b/docs/reference/gdk/tmpl/gdkapplaunchcontext.sgml
@@ -0,0 +1,106 @@
+<!-- ##### SECTION Title ##### -->
+Application launching
+
+<!-- ##### SECTION Short_Description ##### -->
+startup notification for applications
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+GdkAppLaunchContext is an implementation of #GAppLaunchContext that
+handles launching an application in a graphical context. It provides
+startup notification and allows to launch applications on a specific
+screen or workspace.
+</para>
+<example>
+<title>Launching an application</title>
+<programlisting>
+GdkAppLaunchContext *context;
+
+context = gdk_app_launch_context_new (<!-- -->);
+
+gdk_app_launch_context_set_screen (my_screen);
+gdk_app_launch_context_set_timestamp (event-&gt;time);
+
+if (!g_app_info_launch_default_for_uri ("http://www.gtk.org", context, &amp;error))
+  g_warning ("Launching failed: %s\n", error-&gt;message);
+
+g_object_unref (context);
+</programlisting>
+</example>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### TYPEDEF GdkAppLaunchContext ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_display ##### -->
+<para>
+
+</para>
+
+@context: 
+@display: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_screen ##### -->
+<para>
+
+</para>
+
+@context: 
+@screen: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_desktop ##### -->
+<para>
+
+</para>
+
+@context: 
+@desktop: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_timestamp ##### -->
+<para>
+
+</para>
+
+@context: 
+@timestamp: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_icon ##### -->
+<para>
+
+</para>
+
+@context: 
+@icon: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_icon_name ##### -->
+<para>
+
+</para>
+
+@context: 
+@icon_name: 
+
+
diff --git a/gdk/gdkapplaunchcontext.c b/gdk/gdkapplaunchcontext.c
index 04c83b5eb1..15a013b768 100644
--- a/gdk/gdkapplaunchcontext.c
+++ b/gdk/gdkapplaunchcontext.c
@@ -134,7 +134,10 @@ gdk_app_launch_context_set_display (GdkAppLaunchContext *context,
  *
  * Sets the screen on which applications will be launched when
  * using this context. See also gdk_app_launch_context_set_display().
+ *
  * If both @screen and @display are set, the @screen takes priority.
+ * If neither @screen or @display are set, the default screen and
+ * display are used.
  *
  * Since: 2.14
  */
@@ -163,6 +166,10 @@ gdk_app_launch_context_set_screen (GdkAppLaunchContext *context,
  * <ulink url="http://www.freedesktop.org/Standards/wm-spec">Extended 
  * Window Manager Hints</ulink>. 
  *
+ * When the workspace is not specified or @desktop is set to -1, 
+ * it is up to the window manager to pick one, typically it will
+ * be the current workspace.
+ *
  * Since: 2.14
  */
 void
@@ -178,7 +185,12 @@ gdk_app_launch_context_set_desktop (GdkAppLaunchContext *context,
  * @timestamp: a timestamp
  *
  * Sets the timestamp of @context. The timestamp should ideally
- * be taken from the event that triggered the launch.
+ * be taken from the event that triggered the launch. 
+ *
+ * Window managers can use this information to avoid moving the
+ * focus to the newly launched application when the user is busy
+ * typing in another window. This is also known as 'focus stealing
+ * prevention'.
  *
  * Since: 2.14
  */
@@ -218,11 +230,14 @@ gdk_app_launch_context_set_icon (GdkAppLaunchContext *context,
  * @context: a #GdkAppLaunchContext
  * @icon_name: an icon name, or %NULL
  *
- * Sets the icon for applications that are launched with this
- * context. The @icon_name will be interpreted in the same way 
- * as the Icon field in desktop files. 
- * See also gdk_app_launch_context_set_icon(). If both @icon 
- * and @icon_name are set, the @icon_name takes priority.
+ * Sets the icon for applications that are launched with this context. 
+ * The @icon_name will be interpreted in the same way as the Icon field 
+ * in desktop files. See also gdk_app_launch_context_set_icon(). 
+ *
+ * If both @icon and @icon_name are set, the @icon_name takes priority.
+ * If neither @icon or @icon_name is set, the icon is taken from either 
+ * the file that is passed to launched application or from the #GAppInfo 
+ * for the launched application itself.
  * 
  * Since: 2.14
  */
-- 
2.30.2